Error code docs: render the ably-common registry into the docs site by lmars · Pull Request #3458 · ably/docs

lmars · 2026-07-05T17:06:24Z

Summary

Renders the Ably error-code registry (introduced in ably-common#348) into the docs site: a documentation page per error code plus a browsable index, all sourced from ably-common/errors/codes/*.md.

Detail page — /docs/platform/errors/codes/<code>: heading <code>: <title>, the stable identifier as a soft sub-title, the summary as the primary description, then the detail body (causes / how to resolve).
Index — /docs/platform/errors/codes: one section per code (linked code: title heading, identifier, summary), replacing the old hand-maintained codes.mdx.

Screenshots

Index page

Detail page (summary only)

Detail page (summary + body)

How it works

The pages are generated and committed, not built at runtime:

bin/generate-error-pages.ts (yarn generate:errors) reads the ably-common submodule and writes the MDX pages under src/pages/docs/platform/errors/codes/. Each carries a hidden {/* DO NOT EDIT */} MDX comment.
Committing the output means the site build/deploy needs no submodule (CircleCI's checkout doesn't init submodules — build-time generation would silently emit nothing).
A CI job (check-error-docs) inits the submodule, regenerates, and fails on any diff, so the committed pages can't drift from the registry or be hand-edited.

The two commits are split as machinery (submodule, generator, CI, component changes, link migrations) and generated pages (the 254 pages + index).

Supporting changes

PageHeader gains an optional subtitle slot; MDXWrapper renders frontmatter.identifier there.
Error-code detail pages resolve to the Platform "Error codes" nav entry, so they show the Platform sidebar.
Footer "Edit on GitHub" points error-code pages at their ably-common source file (hidden on the generated index).
The 8 inline links to …/errors/codes#<code> now point at the detail pages; the index keeps the /docs/platform/errors/codes URL (old /docs/errors/codes redirect preserved) and carries #<code> anchors for old deep links.

Depends on / follow-ups

Depends on ably-common#348. The submodule is pinned to that PR's commit. Once it merges, bump the submodule to ably-common main — until then the "Edit on GitHub" links target main and 404.
Deferred (tracked separately): SDK codegen migrations (ably-go / ably-ruby / ably-ai-transport-js) and the help.ably.io/error/{code} → /docs/platform/errors/codes/<code> redirect cutover.

Verification

Full gatsby build succeeds: 254 detail pages + index emitted, LLM-markdown export and redirects generated.
All 255 pages compile with the MDX + GFM config the site uses; the "DO NOT EDIT" banner is confirmed absent from rendered HTML.
Lint and typecheck clean on all changed files.

Add the review-app label to spin up a review deployment. Tag @team-deved for review.

🤖 Generated with Claude Code

Render the Ably error-code registry into the docs site as a page per code plus an index, sourced from the ably-common registry. - Add ably-common as a pinned git submodule (source of the registry). - bin/generate-error-pages.ts (yarn generate:errors): reads ably-common/errors/codes/*.md and writes committed MDX pages under src/pages/docs/platform/errors/codes/ plus the codes.mdx index, each carrying a "DO NOT EDIT" MDX comment. Committing the output means the site build/deploy needs no submodule (CircleCI checkout doesn't init submodules). - CI check-error-docs: inits the submodule, regenerates, and fails on any diff so the committed pages can't drift from the registry or be hand-edited. - PageHeader gains an optional subtitle slot; MDXWrapper renders the error identifier there as the sub-title. - Error-code detail pages resolve to the Platform "Error codes" nav entry (layout-context) so they show the Platform sidebar. - Footer "Edit on GitHub" points error-code pages at their ably-common source file, and is hidden on the generated index. - Migrate 8 inline links from /docs/platform/errors/codes#<code> to the new /docs/platform/errors/codes/<code> detail pages. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Committed output of `yarn generate:errors` (bin/generate-error-pages.ts): one page per code at /docs/platform/errors/codes/<code> and the index at /docs/platform/errors/codes (replacing the hand-maintained codes.mdx). Each file carries a hidden "DO NOT EDIT" MDX comment. Regenerate and commit after bumping the ably-common submodule; the check-error-docs CI job fails if these are out of date or hand-edited. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

coderabbitai · 2026-07-05T17:06:33Z

Important

Review skipped

Auto reviews are disabled on this repository. Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: Repository UI

Review profile: CHILL

Plan: Pro

Run ID: 7e6d007e-4a6d-476c-9ca7-4912c3be4f22

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

🔍 Trigger review

✨ Finishing Touches

🧪 Generate unit tests (beta)

Create PR with unit tests
Commit unit tests in branch error-docs

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

_{Comment @coderabbitai help to get the list of available commands.}

m-hulbert

This mostly LGTM. Just a few comments/suggestions:

I think the index of error codes would work better as a table, rather than 100s of headings. Debatable whether it's 1 continuous table or we split it into error code batches for easier navigation.
I think a design pass at the sub-header identifier is probably in order as it looks a bit odd.
I think the identifier should probably be output to the .md version of each page (configured in data/onPostBuild/transpileMdxToMarkdown.ts) for LLM consumption.

Responds to review feedback on the error-code docs: - Index is now a table per thousands bucket (40xxx, 80xxx, …) instead of 254 headings, for easier navigation. The identifier sits beneath the code in smaller text (keeping the column narrow), and each row keeps a numeric anchor so old `…/codes#<code>` deep links still resolve. - Detail page URLs now carry the identifier: `/docs/platform/errors/codes/<code>-<identifier>` (hyphenated). The bare `…/codes/<code>` URL redirects to it, so inline links and the error `href` (which use the code alone) keep working. - transpileMdxToMarkdown outputs the identifier ("Identifier: `<id>`") into the .md LLM version of each page, which otherwise loses it (it is rendered from frontmatter on the HTML page). Adds tests. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Committed output of `yarn generate:errors`: detail pages renamed to `<code>-<identifier>.mdx` (adding the bare-code redirect_from), and the index rebuilt as batched tables. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

lmars · 2026-07-09T11:38:02Z

Thanks @m-hulbert! Addressed points 1 and 3 (commits 117aa30 + 4960edf):

1. Index as a table, split into batches. The index is now one table per thousands bucket (10xxx, 40xxx, 80xxx, …) instead of 254 headings, so it's navigable by range. Each row links to the code's page, with the identifier beneath the code in smaller text (keeps the column narrow), and a per-row <a id="<code>"/> anchor so old …/codes#<code> deep links still resolve.

3. Identifier in the .md version. transpileMdxToMarkdown.ts now outputs Identifier: \`beneath the title in each generated.md`, so it's available for LLM consumption (it was previously rendered only from frontmatter on the HTML page). Added unit tests.

Also included a related change: detail-page URLs now carry the identifier — /docs/platform/errors/codes/<code>-<identifier> (e.g. …/40142-token-expired) — with the bare …/codes/<code> redirecting to it, so code-only inline links and the error href still resolve.

2. Design pass on the identifier sub-header. Not done yet — leaving that as a follow-up.

Verified with a full gatsby build: 254 slug pages + the batched index, the bare-code redirects, and the .md identifier output. The review app will refresh with these changes.

🤖 This reply was generated with Claude Code

lmars and others added 2 commits July 5, 2026 18:02

lmars added the review-app Create a Heroku review app label Jul 5, 2026

lmars requested a review from a team July 5, 2026 17:28

ably-ci temporarily deployed to ably-docs-error-docs-mlmijapqd July 5, 2026 17:28 Inactive

lmars mentioned this pull request Jul 7, 2026

Error code documentation registry ably/ably-common#348

Merged

m-hulbert reviewed Jul 7, 2026

View reviewed changes

lmars and others added 2 commits July 9, 2026 12:34

ably-ci deployed to ably-docs-error-docs-mlmijapqd July 9, 2026 11:34 View deployment

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Error code docs: render the ably-common registry into the docs site#3458

Error code docs: render the ably-common registry into the docs site#3458
lmars wants to merge 4 commits into
mainfrom
error-docs

lmars commented Jul 5, 2026 •

edited

Loading

Uh oh!

coderabbitai Bot commented Jul 5, 2026 •

edited

Loading

Review skipped

Uh oh!

m-hulbert left a comment

Uh oh!

lmars commented Jul 9, 2026

Uh oh!

Reviewers

Assignees

Labels

Milestone

Development

Uh oh!

3 participants

Uh oh!

Conversation

lmars commented Jul 5, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Screenshots

Index page

Detail page (summary only)

Detail page (summary + body)

How it works

Supporting changes

Depends on / follow-ups

Verification

Uh oh!

coderabbitai Bot commented Jul 5, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Review skipped

Uh oh!

m-hulbert left a comment

Choose a reason for hiding this comment

Uh oh!

lmars commented Jul 9, 2026

Uh oh!

Reviewers

Assignees

Labels

Milestone

Development

Uh oh!

3 participants

lmars commented Jul 5, 2026 •

edited

Loading

coderabbitai Bot commented Jul 5, 2026 •

edited

Loading